home *** CD-ROM | disk | FTP | other *** search
/ Internet Info 1994 March / Internet Info CD-ROM (Walnut Creek) (March 1994).iso / networking / info-service / gopher / Rice_CMS / gopher24.readme < prev    next >
Encoding:
Text File  |  1993-08-20  |  21.2 KB  |  482 lines
  1.  
  2.   This is the README file for CMS Gopher 2.4.2 (ver 2 rel 4 mod 2).
  3.   If you have any questions,  send e-mail to  troth@rice.edu.
  4.   You can acquire updates and refreshes via Gopher from the
  5.   Gopher server at  ricevm1.rice.edu.   This is VRM 2.4.2.
  6.  
  7.         Copyright 1993 Richard M. Troth.   This software was developed
  8.         with resources provided by Rice University and is intended
  9.         to serve Rice's user community.   Rice has benefitted greatly
  10.         from the free distribution of software,  therefore distribution
  11.         of unmodified copies of this material is not restricted.
  12.         You may change your own copy as needed.   Neither Rice
  13.         University nor any of its employees or students shall be held
  14.         liable for damages resulting from the use of this software.
  15.  
  16.   You will need CMS Pipelines.                  (5785-RAC)
  17.   You will need VM TCP/IP, V2 or later.         (5735-FAL)
  18.   You will need REXX/Sockets (supplied), a part of VM TCP/IP.
  19.  
  20.  ------  ------  ------  ------  ------  ------  ------  ------  ------
  21.  
  22.   PLEASE NOTE:   when fetching MODULEs and VMARC files from some hosts,
  23.   the record structure must be restored.   If you pick-up a MODULE from
  24.   a UNIX FTP host,  you must  "deblock" it back into its CMS form with:
  25.  
  26.         PIPE < program MODRAW | DEBLOCK CMS | > program MODULE A
  27.  
  28.   For VMARC files,  reblock to  Fixed 80  with:
  29.  
  30.         PIPE < package VMARCRAW | FBLOCK 80 00 | > package VMARC A
  31.  
  32.   and then  "vmarc unpk"  the package.
  33.  
  34.   CMS TAR files are true binary and need not be re-blocked.
  35.   MODULEs and other record oriented files archived into a CMS TAR
  36.   file or tape will be correctly re-blocked by CMS TAR.
  37.  
  38.  ------  ------  ------  ------  ------  ------  ------  ------  ------
  39.  
  40.   See  GOPHER24 FILELIST  for a complete list of files.
  41.  
  42.   Experimental Forms Oriented Feedback support is included.
  43.  
  44.   To display GIFs with CMS Gopher, get the VMGIF package from
  45.   LISTSERV at BLEKUL11,  or via Anonymous FTP to cc1.kuleuven.ac.be.
  46.  
  47.   To process MIME type objects with CMS Gopher, get the MIME package.
  48.   (should be found wherever you acquired this Gopher package)
  49.  
  50.   The gem  EXPAND REXX  (expand TABs) has been replaced by
  51.   the gem  UNTAB REXX,  which should soon be replaced by a
  52.   CMS Pipelines built-in function  (probably CMS 10).
  53.  
  54.   Dieter Gobbers and Alan Flavell graciously created and supplied a
  55.   German message repository.   Other languages would be most welcome.
  56.   Rice's CMS Gopher client is the only one I know of that is mult-lingual.
  57.  
  58.   You can (and should) get the full PH PACKAGE from
  59.   LISTSERV at IRISHVMA or from Nick LaFlamme, NLAFLAMM at IRISHVMA.
  60.  
  61.   After a year and half, Gopher's HELP files are still crummy.
  62.  
  63.  ------  ------  ------  ------  ------  ------  ------  ------  ------
  64.  
  65. Client Features:
  66.  
  67.         o   displays GIFs via the VMGIF package from BLEKUL11 (not supplied)
  68.         o   processes MIME objects via optional MIME package (not supplied)
  69.         o   handles WAIS searched menus
  70.         o   interacts with CSO/qi phonebook servers via PH EXEC
  71.         o   can use any file viewer you desire
  72.         o   "next item" key
  73.         o   bookmarks
  74.         o   multi-lingual (German and American English supplied)
  75.  
  76. Server Features:
  77.  
  78.         o   hierarchical menus with or without SFS
  79.         o   both static and dynamic files (latter created by pipes)
  80.         o   offers WAIS-like searched menus internally with WISHLP tool
  81.  
  82.  ------  ------  ------  ------  ------  ------  ------  ------  ------
  83.  
  84. WELCOME
  85.  
  86. Welcome to GopherSpace!   I hope you enjoy your trek.
  87.  
  88. If you have any questions about the Rice CMS Gopher client or server
  89. or if you have trouble setting them up,  send e-mail to Rick Troth,
  90. troth@rice.edu,  or call me at (713) 285-5148.   There's also a dis-
  91. cussion list to which you may subscribe:  vmgopher@pucc.princeton.edu.
  92. Subscribe with a note to listserv@pucc.princeton.edu with the following:
  93.  
  94.         subscribe vmgopher first-name last-name
  95.  
  96. The InterNet Gopher  (or just "gopher" for short)  is a simple
  97. information dispersal tool based on TCP/IP.   It is an example
  98. of the kind of seemless interoperability that is possible
  99. when we (programmers) actually try to do things right.
  100. The Gopher protocol doesn't care about host operating systems,
  101. their file storage formats,  character sets,  or command suite
  102. (or lack thereof).
  103.  
  104. CMS Gopher is based on three very strong tools:  the REXX language,
  105. Arty Ecock's REXX/Sockets,  and CMS Pipelines.   As a programmer,
  106. I literally went to tears over how well these three work together.
  107.  
  108. More warm fuzzies later.   You need to unpack this thing.
  109.  
  110.  ------  ------  ------  ------  ------  ------  ------  ------  ------
  111.  
  112. SETTING UP THE CLIENT
  113.  
  114. Don't access an old version of Gopher in front of a new version.
  115.  
  116. You may have some special method of giving users access to your
  117. CMS applications.   At Rice,  we keep most applications on their own
  118. minidisk,  and leave a  "wrapper" EXEC on a  public, always accessed
  119. minidisk  (our X disk).   The client is GOPCLI.   Whatever wrapper you
  120. create should  STATE GOPCLI EXEC  and access the right disk or SFS
  121. directory if it's missing.
  122.  
  123. You may want to tailor a couple of environment variables.   There's no
  124. CONFIG file for the client in CMS Gopher 2.4.   All configuration data
  125. are kept in user GLOBALVs.   See  HELP GOPHER  for a list of user-settable
  126. Global Variables.   HOST and NAME are two that many people like to predefine.
  127. HOST is the TCP/IP host computer where your  "top level"  gopher server runs.
  128. NAME is the name of that  "top level"  menu.   (there's no way in the
  129. Gopher protocol for a menu to name itself;  all menus and plain files
  130. are named by the menu that references them,  so you need to set NAME
  131. or you'll get  "(root menu)",  harmless but ugly)
  132.  
  133. Note that the client reserves the fileid  VMGOPHER DOCUMENT  for times
  134. when it needs to write a file to CMS disk if it can't make sense of
  135. the name provided by the current server.  (servers may be running on
  136. UNIX, VAX/VMS, MVS, PC/MS-DOS, or even Macintosh)
  137.  
  138. PICTURES
  139.  
  140. CMS Gopher 2.4 supports the gopher "image" (type I) files.   Presently,
  141. the only format displayable is GIF files using the VMGIF package available
  142. from the fine folks at BLEKUL11:
  143.  
  144.         tell listserv at blekul11 get vmgif package
  145.  
  146. MIME objects
  147.  
  148. CMS Gopher 2.4 supports MIME type items.   All you need is for the
  149. MIME package  (found wherever you picked-up this Gopher package)
  150. to be available on an accessed minidisk or directory.
  151. If  MIMEREAD REXX  is missing,  Gopher presents MIME objects as text.
  152.  
  153.  ------  ------  ------  ------  ------  ------  ------  ------  ------
  154.  
  155. SETTING UP THE SERVER
  156.  
  157. The server is GOPSRV.   Setting it up is trickier than setting up the
  158. client because you not only have to create a virtual machine for it to
  159. run in,  but you also have to take the time to structure your gopher data
  160. nicely.   See  GOPHERD DIRECT  for an example CP Directory entry.
  161. You can have multiple gopher servers.
  162.  
  163. If you don't have SFS,  you can create a hierarchical set of menus using
  164. FILELISTs.   Some VMers insist on using FLIST.   They say it's faster
  165. than FILELIST.   Fine.   But FILELIST lets you save and load FILELISTs
  166. such that you can easily bundle files together almost as easily as with
  167. true directories.   If you do have SFS,  you can let it do the work of
  168. maintaining your menu hierarchy.
  169.  
  170. Gopher FILELISTs are made up of lines of the form:
  171.  
  172.         fn  ft  fm  path  "name"  type
  173.  
  174.                 where fn/ft/fm are the filename, filetype, and filemode
  175. of the file being referenced.   The path is really only the last part of
  176. the gopher "selector string" pointing to this file.   The paths of all
  177. parent menus are automatically prepended.   The name (must be in quotes)
  178. is what the user sees in the menu referencing this file.   The type is a
  179. one-digit type indicator,  any of:
  180.  
  181.                 0       this file is plain-text
  182.                 1       this item is a menu
  183.                 4       this is a Macintosh file
  184.                 5       this is an MS-DOS file
  185.                 6       this is a UUEncoded file
  186.                 7       this item is a search on a menu
  187.                 9       this is a binary file
  188.                 I       image (graphic; typically GIF)
  189.                 s       a sound file
  190.                 M       a MIME object
  191.                 F       a forms-oriented feedback item
  192.  
  193. There are other types,  but these are the ones most useful in FILELISTs.
  194.  
  195. Everything except the filename is optional.   Filetype, filemode, path,
  196. name and type may all be omitted,  in which case the server will choose.
  197. The first character of each line in a Gopher FILELIST must be either
  198. a blank or an asterisk,  the latter denoting a comment.   With care,
  199. you can in fact use a Gopher FILELIST as input to CMS' FILELIST EXEC.
  200.  
  201. I mentioned the menu type, digit 1.   Please note that you do NOT specify
  202. a menu within a menu by marking some file as type 1,  but rather by using
  203. a special filetype "*".   The server will automatically mark it as type 1.
  204.  
  205. The  "root"  menu is defined by <userid> FILELIST,  where <userid>
  206. is the name of your gopher server virtual machine,  typically GOPHERD.
  207. You can override this and other parameters in GOPHERD CONFIG.
  208.  
  209. So,  making a long story longer,  to setup your gopher server,  define
  210. virtual machine GOPHERD,  give it access to your local gopher disk,
  211. create GOPHERD FILELIST listing one or more files you wish to serve-out,
  212. then  CP AUTOLOG GOPHERD.
  213.  
  214. This "picture" might illustrate what I'm trying to say:
  215.  
  216.         GOPHERD virtual machine
  217.                \
  218.                 GOPHERD  FILELIST "root menu"
  219.                                  \
  220.                                   GOPHERD  README
  221.                                   MYFILE   DOCUMENT
  222.                                   SUBMENU  FILELIST
  223.                                                    \
  224.                                                     FILE1    DOCUMENT
  225.                                                     FILE2    DOCUMENT
  226.                                                     FILE3    DOCUMENT
  227.  
  228.  
  229. There is a CONFIG file,  which you can tailor as needed.   With the 2.4
  230. server,  the only variables meaningful in the config file are  LOGPIPE,
  231. PORT,  and  ROOT.   PORT defaults to 70.   ROOT defaults to the virtual
  232. machine name  (server's userid).   LOGPIPE defaults to CONSOLE.
  233.  
  234. You will probably want to dedicate port 70 to GOPHERD in your local
  235. PROFILE TCPIP for you TCPIP service virtual machine.   It's also good
  236. to have GOPHERD listed as AUTOLOGged by TCPIP.   Neither of these steps
  237. are required to test GOPHERD;  just run it.   It's pretty harmless.
  238.  
  239. PIPES AND AUTHORIZATIONS
  240.  
  241. A nice way to degrade performance of your gopher server is to create a
  242. NAMES file for a menu.   In spite of the cost,  this is useful because
  243. you can control access to and/or define CMS Pipelines specifications for
  244. menus and items in the NAMES file.
  245.  
  246. When the server accesses a directory,  it looks for <menu> NAMES.
  247. (this works best with FILELISTs;  if you do it for SFS directories,
  248. consider that the server may access other directories,  releasing the
  249. one that holds your NAMES file,  as it resolves the selector path string)
  250. If <menu> NAMES exists,  the server uses NAMEFIND to process it.
  251. This is best explained by an example:
  252.  
  253.  
  254.         :nick.myfile   :fn.my   :ft.file
  255.                        :auth..rice.edu deny .cuny.edu .gov allow *
  256.                        :pipe.CP Q NAMES | SPLIT /,/
  257.  
  258. For the file  MY FILE,  any host who's InterNet hostname ends in
  259. ".rice.edu"  (all of the Rice campus)  can read it.   Any host who's
  260. InterNet hostname ends with  ".cuny.edu"  or  ".gov"  is prohibited.
  261. Everyone else is then permitted.   If the client is permitted access,
  262. then instead of reading the file  MY FILE,  the server sends the output
  263. of the pipeline  CP Q NAMES | SPLIT /,/  to the client.
  264.  
  265. This can get quite sophisticated.   No,  you do not have to have both
  266. an auth and a pipe in the NAMES file entry.   You can have either one
  267. or neither.   And know that CMS NAMEFIND does not provide a way to
  268. specify the filemode of the NAMES file,  so be careful about menu
  269. name collisions.
  270.  
  271. You can also specify  host, port, path, name, and type  in a NAMES file.
  272. This means that you can use NAMES files in place of GOPLINK files,
  273. but remember that NAMEFIND is going to cost you.
  274.  
  275. Link files?   They let you point to other gopher servers.
  276. See the Q&A section below,  otherwise this section will go on forever.
  277.  
  278. SEARCH ITEM
  279.  
  280. Creating a search item in a menu is easy.   Set it up just like you
  281. would any other sub-menu,  but mark it as Type 7.   Something like:
  282.  
  283.         MYSEARCH FILELIST * whatever "My Own Search Item" 7
  284.  
  285.                 in the parent menu's FILELIST.
  286.  
  287. There's no reason why you can't have the menu as a whole listed
  288. right next to the searched version,  like:
  289.  
  290.         MYSEARCH FILELIST * whatever "My Own Search Item" 7
  291.         MYSEARCH FILELIST * whatever "My Own Search Item (not indexed)"
  292.  
  293. You must also create an index file for this menu.   The easiest way is
  294. by using GOPGEN.   GOPGEN is primarily a tool for making your own mods
  295. to CMS Gopher,  but it also performs the right incantation on WISHLG
  296. (thank's Yossie) to create an index for you.   The server then will
  297. invoke WISHLP (thank's again, Yossie) to list the files that match
  298. the client's search expression.
  299.  
  300.         GOPGEN INDEX MYSEARCH
  301.  
  302. MYSEARCH FILELIST must exist.   All of the files it lists must exist.
  303. You must then put the index file,  MYSEARCH GOPINDEX,  where the server
  304. will access it.
  305.  
  306.  ------  ------  ------  ------  ------  ------  ------  ------  ------
  307.  
  308. FUNCTIONS OF FILES
  309.  
  310. Here's a list of most of the files in the package and their function:
  311.  
  312.       GOPHER   EXEC     "wrapper" EXEC; ensures product disk accessed
  313.       GOPCLI   EXEC     the client
  314.       GOPCLINI EXEC     client initialization (called once from GOPCLI)
  315.       GOPCLISX REXX     handles all TCP/IP "sockets" work for the client
  316.       GOPCLITM REXX     decides what how a given item should be processed
  317.       GOPCLIST REXX     displays connection status,  "Reading ...",  etc
  318.       GOPCLIMB REXX     menu browser
  319.       GOPCLIUI REXX     user input (prompting)
  320.       GOPCLITX REXX     reformats plain-text
  321.       GOPCLIFV REXX     file viewer; may be used stand-alone
  322.       GOPCLIGV REXX     graphics viewer; presently GIFs only
  323.       GOPCLIFI EXEC     returns legal CMS fileid from a gopherspace path
  324.       GVM      EXEC     "DIALed Gopher" client; calls GOPHER to call GOPCLI
  325.       GVM      DIRECT   CP Directory entry for the DIALed Gopher
  326.  
  327.       GOPHERD  EXEC     "wrapper" EXEC for the server; write your own
  328.       GOPSRV   EXEC     the server
  329.       GOPSRVLS REXX     lists files and menus (menus in LISTFILE format)
  330.       GOPSRVRP REXX     gopher path resolution; uses GOPSRVLS output
  331.       GOPSRVMB REXX     menu builder
  332.       GOPSRVGL REXX     gopher "link" processor
  333.       GOPSRVAU EXEC     performs authorization check
  334.       GOPSRVFM EXEC     dummy filemode function for server
  335.       GOPHERD  DIRECT   example CP Directory entry for the server
  336.  
  337.       UNTAB    REXX     expands TAB characters
  338.       PRINT    REXX     similar to CMS PRINT, but a pipe
  339.       A2E      REXX     translate ASCII to EBCDIC
  340.       E2A      REXX     translate EBCDIC to ASCII
  341.       TCPA2E   REXX     A2E, but follows TCP/IP translate tables
  342.       TCPE2A   REXX     E2A, "   "       "      "         "
  343.       STANDARD TCPXLATE suggested ASCII <---> EBCDIC translate tables
  344.       STANDARD TCPXLBIN binary object built from above TCPXLATE
  345.  
  346.       GOPUME   MESSAGES message repository source
  347.       GOPUME   TEXT     message repository object
  348.  
  349.       GOPXEDPR XEDIT    XEDIT profile for XEDIT used as file viewer
  350.       GOPXEDII XEDIT    "item info" command for XEDIT as file viewer
  351.  
  352.       GOPHMARK EXEC     migrates bookmars from 2.3
  353.  
  354.       RXSOCKET MODULE   Arty's wonderful CMS Socket tool
  355.       DISKWRIT MODULE   minidisk need reACCESSing?
  356.       WISHLP   MODULE   Yossie's *fast* search engine
  357.       WISHLG   MODULE   index builder for above
  358.  
  359.       PH       EXEC     Nick LaFlamme's CSO/qi/ph (phonebook) client
  360.  
  361.       GL       EXEC     primitive tool for browsing CMS Gopher FILELISTs
  362.  
  363.       GOPHERCAT EXEC    dumps gopherspace files right onto your console
  364.  
  365.       GOPHERDH REXX     a pipeline stage that interprets CMS HELP
  366.       HELP     NAMES    defines HELP menu to the server using above
  367.  
  368.  ------  ------  ------  ------  ------  ------  ------  ------  ------
  369.  
  370. There is a discussion list,  VMGOPHER@PUCC.Princeton.EDU.
  371. Please join us.   We discuss development and featurs of CMS Gopher.
  372.  
  373. There is another CMS Gopher (both server and client),  popularly called
  374. "the Vienna Gopher",  available from Gerhard Gonter <GONTER@AWIWUW11>.
  375.  
  376.  ------  ------  ------  ------  ------  ------  ------  ------  ------
  377.  
  378. Q:      The basics, documents and FILELIST menus, is fairly easy to grasp,
  379.         but the relationship of a NAMES file and its entries to a FILELIST
  380.         file and its entries is not at all evident to the poor soul that
  381.         just wants to provide an information service without much time
  382.         invested (I.e., without subscribing to VMGOPHER).
  383.  
  384. A:      The easiest way to start is just name some plain-text files in
  385.         GOPHERD FILELIST  (which are available to your GOPHERD service
  386.         machine on an accessed disk or SFS directory).   Then after you're
  387.         comfortable with that,  try some "links"  (filetype GOPLINK) and
  388.         sub-menus  (filetype FILELIST).   Then get into NAMES files.
  389.  
  390. Q:      How to I point to another server/menu?
  391.  
  392. A:      The easiest way is with a "link" file  (filetype GOPLINK).
  393.         When a link file shows-up in any FILELIST,  the contents of
  394.         that file are read and the information specified is presented
  395.         to the client for that particular menu item.
  396.  
  397.         The contents of a GOPLINK file are the same as
  398.         for a UNIX server link file,  of the form:
  399.  
  400.                 Name=Rice University CMS Gopher server
  401.                 Host=ricevm1.rice.edu
  402.                 Port=70
  403.                 Path=1/
  404.                 Type=1
  405.  
  406.         As of 2.4,  GOPLINK file can have more than one link in it.
  407.         (but you will probably find things easier to manage
  408.         if you have just one link per GOPLINK file)
  409.  
  410.         NOTE:   Gopher server link files  MUST  be  RECFM V  or you
  411.                 will get trailing blanks which UNIX servers won't like.
  412.  
  413. Q:      How does a GOPLINK file differ from a "link" in a NAMES file?
  414.  
  415. A:      The NAMES file is far more extensive.   (and exPensive)
  416.         With the CMS Gopher server,  you don't use "link" files to
  417.         override the characteristics of other files in the menu  (as you
  418.         would with a UNIX server).   With the CMS server,  GOPLINK
  419.         files are exclusively used to reference other network (usually
  420.         non-local) resources,  while the NAMES file may apply to local
  421.         files,  which reside on your system OR to remote services.
  422.  
  423. Q:      Some folks have made it seem that their gopher server files
  424.         are free for the taking ...  is there a gopher feature
  425.         to pull these in?
  426.  
  427. A:      To "receive" (keep) an item,  press PF5.   The receive function
  428.         will not overwrite an existing file  (though you can still
  429.         view & SAVE from XEDIT).
  430.  
  431. Q:      GOPHERD should document DISKWRIT in the prolog.
  432.  
  433. A:      GOPHERD uses DISKWRIT to perform the same "reaccess" trick that
  434.         GONE EXEC does when you reconnect.   If disks appear to have
  435.         changed,  they are reACCESSed so that the server has the latest
  436.         revision of any files on those minidisks.
  437.  
  438. Q:      Why are the "STANDARD" translate-table files provided?
  439.         Are these for use with the server?
  440.  
  441. A:      Both server and client.
  442.         The default ASCII <---> EBCDIC translation in VM TCP/IP (FAL)
  443.         is not 100% correct for the majority of the VM/UNIX/VMS/DOS/Mac
  444.         world we live in.   STANDARD TCPXLATE and TCPXLBIN provide
  445.         a 1-for-1 translation between  de-facto "network EBCDIC"
  446.         (codepage 1047)  and  "extended ASCII"  (ISO 8859-1).
  447.  
  448. Q:      If PhoneBk and Search are available, how do we use them?
  449.  
  450. A:      Presently,  CMS GopherD does not support PhoneBk engines.
  451.         Search engine is provided by Yossie Silverman's WISHLG/WISHLP.
  452.         The client (GOPCLI) is happy to utilize such servers on any host.
  453.  
  454. Q:      Some GOPHERs restrict access or output to some clients;  how?
  455.  
  456. A:      Specify an "auth" value in the NAMES file.   The tag :auth.
  457.         allows for control over any object in a menu  (defined by a
  458.         FILELIST and/or NAMES file),  even the menu itself.
  459.  
  460. Q:      Is there anything different about your RXSOCKET?
  461.  
  462. A:      RXSOCKET is supplied because Gopher requires it.
  463.         RXSOCKET was created by Arty Ecock.   He maintains it.
  464.         Rice doesn't have any mods to RXSOCKET,  and Gopher doesn't
  465.         need any special treatment from RXSOCKET.   If you find an
  466.         RXSOCKET packaged with CMS Gopher to be out-of-date,  by all
  467.         means,  use the current one or get the latest from Arty.
  468.         (RXSOCKET will cease to be included with Gopher distribution
  469.         at some yet future date)
  470.  
  471.  ------  ------  ------  ------  ------  ------  ------  ------  ------
  472.  
  473. Thanks to:
  474.  
  475. Yossie Silverman,  Jim Gerland,  Arty Ecock,  Serge Goldstein,
  476. Chuck Boeheim,  Wayne Smith,  Jim Colten,  Nick LaFlamme,
  477. Rich Wiggins,  Martha McConaghy,  John Hartman,  Melinda Varian,
  478. Alan J. Flavell, ...
  479.  
  480. (this list continues to grow,  and some have surely been left out)
  481.  
  482.